Camera Actor Bar, Depth of Field, and 3D Stereo
-----------------------------------------------

You will need to be familiar with the Action Editor mechanics, and
the use of Camera's X/Y axes before this will make much sense ...

There are two features in Imagine, that both "want" to use the length
of the camera's Y axis, to specify an "important" and animatable distance
from the camera:  Depth of Field, and 3D Stereo Image Generation.  In order
to deal with this, and to provide a usable Stage/Action Editor interface
to the (newer) Depth of Field feature, the Camera Actor Bar has been added.
It was added rather late in development, and so its use isn't described in
the manual.

For 3D Stereo, the "important distance", mentioned above, is the distance
from the camera to objects you wish to appear to be "in" the screen of the
monitor, ... i.e. at the surface of the monitor, not in inside or outside.

For Depth of Field, the "distance" is the distance from the camera to objects
which are in perfect focus.

Both features also require you to specify a 2nd size (i.e. distance) too.
For 3D Stereo, it is the distance in the "Imagine world" corresponding to
the viewers "eye separation" -- which, in the past, has been described by
a parameter set in the Preferences Editor, that gives that distance as
a certain fraction (e.g. 0.250) of the monitor width ... and which Imagine
then converted into a proper distance in its coordinate system.  For the
Depth of Field feature, the 2nd size would correspond, in the real world,
to the "effective" radius of the a camera lens ... i.e. to the radius of
a circle at the lens surface that collects all the light that actually
makes it through the lens system, and the camera's "aperture", and gets
focused (however badly) onto the film.

If, you only need one of those features at a time, then in a Camera actor
bar (which you must add), you should click on one of the two checkboxes
at the top of the "info requester", telling Imagine to interpret the
Y axis length as the (1st) "distance" you need to specify ... and then
setup the 2nd size/distance as described below.  If you want to do both
3D Stereo and Depth of Field in the same project, you must set the
"Distance Multiplier" value to a number to multiply the Y axis length
by to get the "other" distance -- i.e. the one you don't select in the
two checkboxes described above.

In the lower part of the requester, there are number slots and checkboxes
to specify the "2nd" distance(s) described above, using one of two methods.
One method is, like the 3D Stereo method of previous versions: as a
fraction of the "width" of the cameras field of view ... which, for
3D Stereo, corresponds to the width of the monitor screen when the
picture is being viewed.  For Depth of Field, its use is similar to,
but not the same as specifying the "Defocus pixels" parameter used in
"quickrenders".  Except that, instead of specifying a pixel count, you
specify a (small) number like "0.01", which when multiplied by the number
of pixels in the (width of) the image you are generating, gives the number
of pixels that you wish the "infinite depth background"  to be out of
focus by (e.g. 6.4 pixels for a 640 wide image, using the 0.01 value above).
The second method is to specify an actual size (for the "2nd" distance)
in Imagine world coordinates.  It is more useful for specifying the radius
of the "effective aperture" used in depth of field, when trying to model
a real world system, than it is for working with 3D Stereo images -- i.e.
in order to model a camera zooming in on something, while still remaining
at the same distance from it ... where, typically, the "depth of field"
quality of the image gets worse in the sense that the background gets
more and more out of focus, while the "subject" of the scene does not.

Finally, at the bottom of the requester is a "Transition Frame Count"
box, used in "animating" the parameters.  Its use is identical to the
similar boxes in the "Globals" and "Light Source" actor bars, described
in the manual.


Some useful mathematical formulas for Depth of Field
----------------------------------------------------

If you have a certain effect you whish to acheive, using depth of field,
it can be difficult, sometimes, to guess which value is appropriate for
the "Aperture Size", or "Defocus" pixel count used to control depth of
field defocusing.  There are, in fact, so many situations we could
imagine (!) here at Impulse, that we couldn't come up with a nice
little requester to aid in calculating a value.  So, we present here,
the basics, and a few special cases ... and hope you can make do.


The Basics:

    In the real world, if you focus on an object that is "Y"
    units away from the plane perpendicular to the line of
    sight, with a "lens system" that gathers light from a circle
    of radius "R", things will be more or less out of focus in
    an amount proportional to the the radius "R", and inversely
    proportional to the width of the field of view, "X", at the
    focus distance, "Y" above.  In fact, points in the "infinite
    background" will be defocused by the fraction "R/X" times the
    actual width of the image produced.  In Imagine, the "X", and
    "Y" values discussed above, correspond to the sizes assigned
    to the camera's X and Y in the "Imagine world", and the "R"
    value is determined either 1) directly if you specify that
    the "aperture size" is a true distance (in world coordinates),
    or 2) indirectly, as "R/X", if you specify that the "aperture
    size" is a fraction of the width of the field of view, or
    3) even more indirectly, as "pixel width" times "R/X", in
    the case of quickrender images, where you give a pixel count.

    Now, there is a particular formula giving the "amount" that
    a point gets defocused (in every direction), when it is not
    in the "infinite background", but is at a distance "D" from
    the plane perpendicular to the line of sight.  And depending
    on whether you want a result in pixels, or as a fraction of
    the image width, or as a particular size that you could compare
    to the size of an object at the "perfect focus" distance, the
    formula is either "image width in pixels times (R/X) times F",
    or "(R/X) times F", or "R times F", respectively, ... where
    the number, "F", to multiply by, is the absolute value of
    "1.0 - (Y/D)".

    From these basics, a number of formulas can be generated,
    depending on the particular circumstances you are confronted
    with.  Some would require you to set the length of the camera's
    Y axis after specifying a pair of distances and the amount of
    defocusing at each distance, and some would allow you to specify
    the length of the Y axis (perfect focus distance), and an amount
    of defocusing at one other distance.

Setting the Y axis length:

    In general, if you have a certain range of distances ...
    D1 to D2, say, and you want things to be equally out of focus
    at D1 and D2, then you should set the camera Y axis size to
    Y=D1*D2/((D1+D2)/2) -- the product of the distances divided by
    thier average.  When D1 and D2 are pretty close to each
    other, that gives a point about right in the middle.  But as
    D2 gets big in comparison with D1, the result moves away from
    the point midway between D1 and D2, and closer to D1.  In fact
    the Y value never gets larger than 2*D1.  But it always remains
    true, that if you guess at a distance to focus at, and you test
    it and see that things are more out of focus at D2 (in the back),
    than at D1, that you need to move the focus point out toward D2
    ... and visa-versa.

Setting the aperture size:

    Once you have decided on where the proper Y axis length -- either
    using the "formula" above, or because you know you want a particular
    point to be in perfect focus, and you have set the camera's X axis
    to get the field of view you want, you can set the aperture size
    properly.  Actually, it isn't necessary to set the X axis size, if
    you specify the amount of defocusing as a number of pixels, or,
    equivalently as a fraction of the width of the image.

    Setting the aperture size to acheive a certain amount of defocusing
    at a particular distance means that you have a certain distance
    in mind -- maybe one of the two distances, D1 or D2, above.
    If the distance is the "infinite background" distance, you can
    just set is using one of the methods described below.  But, if
    it is a "real" distance, D, you need to calculate the absolute
    value of (1 - Y/D), and then divide the value below by it -- which
    should increase it.

    If the "amount of defocusing" you have in mind is a certain number
    of pixels, then you can simply divide the pixel count by the size
    of the image in pixels, enter that number in the camera bar, and
    check the "Aperture Size is Fraction of DOF Width" checkbox.

    If you want to specify the aperture as an "actual size" (and then
    animate the camera's X and Y sizes, say), then you need to multiply
    the value above (the ratio of defocusing pixels to image pixels)
    by the size of the camera's X axis, after you have set up the camera.